ParcelLabel API

How to submit manifests only

Note: This functionality is currently only available for DOMESTIC and INTERNATIONAL INBOUND labels.

The NZ Post Parcel Label API allows customers to use the "manifest only" functionality. This is for senders who use White Labelling integrations where they create the label in their own systems (not via Parcel Label) but are required to send a manifest for each parcel.

Parcel Label "manifest only" mode allows for JSON sending of the manifest.

Resource URL

UAT:

https://api.uat.nzpost.co.nz/parcellabel/v3/labels

Production:

https://api.nzpost.co.nz/parcellabel/v3/labels

A unique consignment_id is returned once the details of the request are stored in the labeling database.

Request Parameters

The request payload parameters are the same as a label request, except for the existense of a manifest_only flag and a tracking_number for the parcel. Since a label is not generated for manifest only requests, non-mandatory parameters pertaining to label orientation, format, dimension, and the like, is not required but is included in the listing for completeness.

Services Codes and Courier Add Ons

Please talk to your business manager to ascertain the appropriate codes to use

Example : Manifest Only request for an International Inbound Economy Returns Parcel (IWXEROLE)

{
    "carrier": "COURIERPOST",
    "orientation": "LANDSCAPE",
    "manifest_only": true,
    "sender_reference_1": "RMA12345",
    "sender_reference_2": "invoice ref",
    "sender_details": {
        "name": "Sender Name",
        "phone": "",
        "email": "info@sendername.com",
        "company_name": "Sender Company",
        "site_code": 17931
    },
    "pickup_address": {
        "company_name": "ABC Returns",
        "building_name": "",
        "unit_type": "",
        "unit_value": "",
        "floor": "",
        "street": "Private Bag 211000",
        "suburb": "Returns Centre",
        "city": "Auckland",
        "country_code": "NZ",
        "postcode": "2154"
    },
    "receiver_details": {
        "name": "Miss Shopper",
        "phone": "0212221598",
        "email": "shopper@gmail.com"
    },
    "delivery_address": {
        "is_collection": false,
        "building_name": "",
        "company_name": "",
        "street": "236 Campbell Road",
        "suburb": "Greenlane",
        "city": "Auckland",
        "country_code": "NZ",
        "postcode": "1061"
    },
    "parcel_details": [
        {
            "tracking_number": "00793266831002284670",
            "service_code": "IWXEROLE",
            "return_indicator": "RETURN",
            "currency": "NZD",
            "dimensions": {
                "length_cm": 30,
                "width_cm": 20,
                "height_cm": 20,
                "weight_kg": 1
            },
            "parcel_contents": [
                {
                    "content_number": 1,
                    "description": "mens shoes",
                    "quantity": 1,
                    "weight_kg": 0.3,
                    "value": 50,
                    "country_code": "CN"
                }, {
                    "content_number": 2,
                    "description": "womens tshirt",
                    "quantity": 1,
                    "weight_kg": 0.15,
                    "value": 35,
                    "country_code": "CN"
                }, {
                    "content_number": 3,
                    "description": "mens socks",
                    "quantity": 2,
                    "weight_kg": 0.1,
                    "value": 10,
                    "country_code": "CN"
                }
            ]
        }
    ]
}

Sample Request - Domestic Overnight CourierPost Outbound service

(An object specifying the label dimensions (in mm) upon which to print the label. If you are passing this object then the value should be 150x100 or 174x100 or an empty string. If it is empty then the default value is 174x100. This field is only mandatory to generate a 150x100 dimensions label.)

{
  "carrier": "COURIERPOST",
  "sender_reference_1": "Order Number 56452",
  "sender_reference_2": "Sales",
  "manifest_only":"true",
  "account_number": "99999999",
  "sender_details": {
  "company_name": "XYZ Widget Company",
  "name": "Bob",
  "phone": "+6425555916",
  "site_code": 96306,
  "email": "bob@xyzwidgets.com"
  },
  "receiver_details": {
    "name": "Alice",
    "phone": "+6424555105",
    "email": "example@example.co.nz"
  },
  "pickup_address": {
    "street": "107 Ransom Smyth Drive",
    "suburb": "Goodwood Heights",
    "city": "Auckland",
    "postcode": "2105",
    "country_code": "NZ"
  },
  "delivery_address": {
    "street": "105 Woodberry Drive",
    "suburb": "Flat Bush",
    "city": "Auckland",
    "postcode": "2016",
    "country_code": "NZ"
  },
  "parcel_details": [{
    "tracking_number": "00793266831002284670",
    "service_code": "CPOLP",
    "add_ons": [],
    "return_indicator": "OUTBOUND",
    "description": "Medium Box",
    "dimensions": {
      "length_cm": 30,
      "width_cm": 30,
      "height_cm": 30,
      "weight_kg": 2
    }
  }]
}

Response Parameters

Field Name	Description	Mandatory
consignment_id	Unique identifier for the consignment if the request is successful.	Yes
message_id	A unique ID for the API call	Yes
success	Returns true if request is successful. Returns false if request is not successful.	Yes

Sample Response

{
  "consignment_id": "S3BGUH",
  "message_id": "bb590940-97b5-11e9-813b-02168927813a",
  "success": true
}